Introduction

What is Modality?

Modality is a free, open-source, hospitality-oriented booking system, currently in development. It will support significant event complexity, unmatched by any existing open or closed-source solution.

Modality will support:

  • short and long events (evenings, days, weekends, weeks)

  • one-time and recurring events

  • partial and full attendance

  • single and multiple venues

  • multiple accommodation locations and types

  • transport options (parking and shuttles)

  • catering options

  • multi-stage payments and discounts

  • detailed statistics

Modality will be useful for:

  • event-oriented organisations

  • hotels

Why the name?

'Modality' is a fusion of two words, 'modular' and 'hospitality', a nod to both the software’s design and purpose.

Status

Modality is in the early stages of active development, and we intend to release a functioning MVP by late-2023.

Whilst the server and data models are complete, the clients have significant work remaining before they are viewable. Currently, only the Back-Office Desktop client (described below) can be compiled and run successfully from the IDE.

Open-source

Modality is licensed under the Apache License Version 2.0, is completely free to use and modify, and is available on GitHub.

The Modality Architecture

Java for the Web

Modality is the first large-scale Java project to use WebFX - a toolkit that transpiles JavaFX applications into pure JavaScript web apps for direct execution in the browser.

Technologies

Modality is developed using the following technologies:

Technology Purpose Version

Java

Codebase

18

JavaFX

Desktop + mobile user interfaces

18

WebFX

Web user interfaces

Latest (Beta)

…​consists of four end-user client applications:

Application Used By Compilation Toolchain

Back-Office Web

Administrator

WebFX + GWT

Back-Office Mobile

Administrator

Gluon

Front-Office Web

Customer

WebFX + GWT

Front-Office Mobile

Customer

Gluon

…​two developer client applications:

Application Used By Compilation Toolchain

Back-Office Desktop

Developer

JavaFX

Front-Office Desktop

Developer

JavaFX

…​one web server:

Application Purpose Version

Vert.x

Interface between client apps and back-end services; serves the SPA

Latest

…​and depends on the following services:

Service Purpose Version

Postgres

Database

14.2

Redis

Session management

6.2.6

Flyway

Database schema updates

Latest

The services are orchestrated by Docker when running Modality on development machines (instructions given later in this document).

Layers

Modality is divided into layers of functionality, shown below:

Layer Repository Java Modules

Business Logic (top layer)

modality

modality-event, modality-hotel, modality-restaurant, modality-catering

Ecommerce

modality

modality-ecommerce

CRM

modality

modality-crm

Base

modality

modality-base

WebFX Stack

webfx-stack

webfx-stack

WebFX (bottom layer)

webfx

webfx-kit

Business logic

The highest layer of the architecture consists of business-specific modules implementing logic for events, hotels, restaurants etc. This is a customisable layer, and developers can choose to add only the modules they need, as well as provide their own.

Ecommerce

The next layer down is the ecommerce layer. This provides a generic domain model for ecommerce, which models sales, accounts etc. It is the location for payment gateway integration and ecommerce-specific UIs.

CRM

The CRM layer provides the essential CRM features, including customer accounts, integrated mailing system etc.

Base

The Base layer is a fully operational implementation of the WebFX Stack layer beneath, based on the Postgres database. This layer is a pure technical solution that isn’t bound to any specific domain, and so is large in application scope.

WebFX Stack

The WebFX Stack layer provides an opinionated framework for developing enterprise applications with WebFX. This layer is responsible for communication between client and server (using a WebSocket bus), UI routing, ORM, push notification, auth, i18n, etc. Interfaces in all cases, but not always full implementations, allowing this layer to be adapted to any kind of system.

Unlike most Java frameworks, this layer works principally on the client side, following the trend initiated by mobile apps where most of the application code has been moved to the client and can run offline.

It is designed to work with JavaFX (for example, i18n provides JavaFX bindings for use with any kind of control; and the authorisation framework automatically enables/disables and shows/hides controls depending on user access).

WebFX

WebFX is the foundation layer, providing a web port of JavaFX (in the webfx-kit module) that can be compiled by GWT together with your application code. It is a Java-based cross-platform solution that can be used in any domain.

All-Layer Aggregation

Modality ships with the modality-all module, which aggregates together the full set of modules across all layers, for use by developers right away.

The Modality Apps

Web apps

Modality uses WebFX to transpile it’s JavaFX codebase into a single-page application for direct execution in the browser. No server-side rendering, and no plugins required.

Mobile apps

Modality uses the Gluon toolchain to compile the codebase into native, installable apps ready for inclusion into the Google Play and Apple App stores.

Desktop apps

Modality also provides desktop apps, which have exactly the same UI as the web apps generated from the same source. This is useful for developers, allowing Java code to be rapidly developed and tested via the desktop, before subsequent transpilation into JavaScript and mobile (which takes time).

Installation

1. Install Java JDK

Modality is developed entirely in the Java language, and requires at least JDK 17+. Check whether this is installed:

java --version

If it is not installed, or is an older version, please refer to this guide.

2. Install WebFX CLI

We use the WebFX CLI to compile Modality for the web. Please follow this guide to install it.

3. Install IntelliJ IDEA

We develop Modality using the free, community edition of IntelliJ IDEA, and recommend you install this if you do not already have an IDE. IntelliJ allows you to easily compile and run the Modality server and clients, for the purpose of local development and testing.

All subsequent IDE-based examples given in this documentation will be based on IntelliJ.

4. Install Docker

During development, Modality uses Docker for all external services, including the database and the in-memory datastore for sessions.

Please install Docker Desktop on your local machine if you do not have it already. If using a Mac, the easiest way is to install using brew. Please provide Docker with a minimum of 8GB of RAM, ideally more.

Insufficient RAM may result in java.lang.OutOfMemoryError errors when importing the modality-dev-db.

5. Install Git

A git client is needed to retrieve the Modality codebase from GitHub. Check if git is installed:

git --version

If it is not installed, you may wish to refer to this guide.

6. Create the Modality root

mkdir -vp modality
export MODALITY_ROOT=${PWD}/modality

7. Clone the codebase

Git clone the Modality codebase via the terminal (or IntelliJ etc):

cd $MODALITY_ROOT
git clone https://github.com/modalityone/modality.git .

8. Unzip the development database

The Modality codebase includes a 15Mb zip file of example data, that makes it easier for developers to navigate around the running system. Execute the following commands to unzip the database, ready for later ingestion into Postgres:

cd $MODALITY_ROOT/modality-base/modality-base-server-datasource/src/main/resources
unzip db-dev/V0001__modality_dev_db.sql.zip -x '__MACOSX/*' -d db/

9. Prepare Docker environment variables

Environment variables store the Postgres database name, username and password. Defaults are provided in the .env-template. Use this template file as the basis for your Docker-based configuration, by creating an .env file from it. You may leave the defaults, or provide new values accordingly:

cd $MODALITY_ROOT/docker
cp .env-template .env
source .env # make the environment variables available to the shell

10. Build the Docker containers

cd $MODALITY_ROOT/docker
docker-compose build --no-cache

11. Start the containers to build the database

cd $MODALITY_ROOT/docker
docker-compose up

Configure Modality for Development

Resolve all Modality Dependencies

Open Modality in IntelliJ and wait for all dependencies to be automatically resolved:

resolve dependencies 1

Modality Server

In order to run any of the Modality client applications, the Modality Server should first be running. The Modality Server is a Vert.x server that proxies requests to the database and is responsible for establishing and maintaining user sessions.

The easiest way to stand up the server locally is to create an application run configuration in the IDE.

In the IntelliJ menu, click Run → Edit Configurations to display the following dialog, and populate with the same details:

run configuration modality server 1
run configuration modality server 2

Click 'OK' to save the configuration and close the dialog.

Back-Office Desktop

The Back-Office Desktop client is an application used by developers of Modality, and emulates the web user interface used by administrators of the system.

Create another run configuration and populate it with the details given in the screenshot below:

run configuration modality back office 1

Click 'OK' to save the configuration and close the dialog.

Front-Office Desktop

The Front-Office Desktop client is not yet implemented.

Build & Run Modality on Development

The Modality clients run independently of each other, but all require the Modality Server to be running, which in turn requires Docker to be running the service containers described above. Therefore, the first two steps below are mandatory before running one or more of the Modality clients locally.

Docker *

Ensure that Docker is running:

cd $MODALITY_ROOT/docker
docker-compose up

Modality Server *

Build and run the server by executing its run configuration:

run modality server locally 1

Back-Office Desktop

Build and run the Back-Office Desktop client by executing its configuration:

run modality back office desktop locally 1

The Back-Office Desktop client will then be ready to use:

modality back office desktop 1
modality back office desktop 2
modality back office desktop 3
modality back office desktop 4
modality back office desktop 5
modality back office desktop 6
modality back office desktop 7
modality back office desktop 8
modality back office desktop 9

Back-Office Web

1 First build the index.html file: 
cd $MODALITY_ROOT
webfx build --gwt
2 Then locate the resultant index.html file on the filesystem: 
webfx build --gwt --locate
3 In the IntelliJ Project window, navigate to the index file and double click.
modality project window index html 1
1 Hover the mouse over the index.html source code to display the browser options.
modality project window index html 2
1 Click on one of the browser icons to run the index.html in a browser.

Back-Office Mobile

Full instructions (and limitations) for compiling the codebase to native Android and iOS apps are available on the WebFX documentation site here.

Front-Office Desktop

The Front-Office Desktop client is not yet implemented.

Front-Office Web

The Front-Office Web client is not yet implemented.

Front-Office Mobile

The Front-Office Mobile client is not yet implemented.

Modality Database

All database setup scripts are stored in the $MODALITY_ROOT/modality-base/modality-base-server-datasource/src/main/resources/db-pristine/ folder, and are numbered in order of execution. They should be copied into the $MODALITY_ROOT/modality-base/modality-base-server-datasource/src/main/resources/db/ deployment folder where they will then be executed by the Flyway container, which runs on Docker startup. All the data will then be stored on the host, in directory:

$MODALITY_ROOT/docker/data/postgres/*

This provides persistence, and the container can be safely shut down and restarted without losing data.

Any new database scripts must be:

1 added to the $MODALITY_ROOT/modality-base/modality-base-server-datasource/src/main/resources/db-pristine/ folder
2 named according to the convention used in the folder: V{latest-number+1}__{desc}.sql
3 copied into the $MODALITY_ROOT/modality-base/modality-base-server-datasource/src/main/resources/db/ deployment folder
4 executed by Flyway by restarting Docker: 
cd $MODALITY_ROOT/modality-base/modality-base-server-datasource/src/main/resources/
.
# Create the new SQL file and copy to the deployment directory
touch db-pristine/V0100__new_table.sql
cp db-pristine/V0100__new_table.sql db/V0100__new_table.sql
.
# Now restart Docker
cd $MODALITY_ROOT/docker
docker-compose down
docker-compose up

Modality Session

The session data is controlled by the docker-based Redis container and is not persisted locally. The data persists only as long as the container is running.

Using Docker

Connect to the Docker database container

Connection is easily made via any Postgres client (e.g. DBeaver). Use the following credentials (contained within the docker/.env-template file):

  • Server: 127.0.0.1

  • Port: 5432

  • Database: modality

  • User: modality

  • Password: modality

Connect to the Docker session container

Connection can be made through the Docker terminal:

cd $MODALITY_ROOT/docker
docker exec -ti session /bin/sh
redis-cli
keys *

Shut down Docker

cd $MODALITY_ROOT/docker
docker-compose down

Prune Docker content

Sometimes you will want a pristine Docker environment. The simplest way to do this is:

cd $MODALITY_ROOT/docker
docker-compose down
docker ps -a # Lists all Docker containers
docker rm <container-id> # Remove any docker containers listed
docker images # Lists all Docker images
docker image rm <image-id> # Remove any docker images listed
docker volume ls # Lists all Docker volumes
docker volume rm <volume-id> # Remove all docker volumes listed
docker system prune # Removes build cache, networks and dangling images
rm -rf data # Removes locally stored database tables

You can now rebuild the Docker containers:

docker-compose build --no-cache
docker-compose up

Deploy Modality to Heroku

Procedures for this coming soon!

PDF version

Here is the PDF version of this documentation.